<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- This file documents the use of the GNU compilers.

Copyright © 1988-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<title>__sync Builtins (Using the GNU Compiler Collection (GCC))</title>

<meta name="description" content="__sync Builtins (Using the GNU Compiler Collection (GCC))">
<meta name="keywords" content="__sync Builtins (Using the GNU Compiler Collection (GCC))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Indices.html" rel="index" title="Indices">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="C-Extensions.html" rel="up" title="C Extensions">
<link href="_005f_005fatomic-Builtins.html" rel="next" title="__atomic Builtins">
<link href="Offsetof.html" rel="prev" title="Offsetof">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
kbd.key {font-style: normal}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>


</head>

<body lang="en_US">
<div class="section-level-extent" id="g_t_005f_005fsync-Builtins">
<div class="nav-panel">
<p>
Next: <a href="_005f_005fatomic-Builtins.html" accesskey="n" rel="next">Built-in Functions for Memory Model Aware Atomic Operations</a>, Previous: <a href="Offsetof.html" accesskey="p" rel="prev">Support for <code class="code">offsetof</code></a>, Up: <a href="C-Extensions.html" accesskey="u" rel="up">Extensions to the C Language Family</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="Legacy-_005f_005fsync-Built_002din-Functions-for-Atomic-Memory-Access"><span>6.54 Legacy <code class="code">__sync</code> Built-in Functions for Atomic Memory Access<a class="copiable-link" href="#Legacy-_005f_005fsync-Built_002din-Functions-for-Atomic-Memory-Access"> &para;</a></span></h3>

<p>The following built-in functions
are intended to be compatible with those described
in the <cite class="cite">Intel Itanium Processor-specific Application Binary Interface</cite>,
section 7.4.  As such, they depart from normal GCC practice by not using
the &lsquo;<samp class="samp">__builtin_</samp>&rsquo; prefix and also by being overloaded so that they
work on multiple types.
</p>
<p>The definition given in the Intel documentation allows only for the use of
the types <code class="code">int</code>, <code class="code">long</code>, <code class="code">long long</code> or their unsigned
counterparts.  GCC allows any scalar type that is 1, 2, 4 or 8 bytes in
size other than the C type <code class="code">_Bool</code> or the C++ type <code class="code">bool</code>.
Operations on pointer arguments are performed as if the operands were
of the <code class="code">uintptr_t</code> type.  That is, they are not scaled by the size
of the type to which the pointer points.
</p>
<p>These functions are implemented in terms of the &lsquo;<samp class="samp">__atomic</samp>&rsquo;
builtins (see <a class="pxref" href="_005f_005fatomic-Builtins.html">Built-in Functions for Memory Model Aware Atomic Operations</a>).  They should not be used for new
code which should use the &lsquo;<samp class="samp">__atomic</samp>&rsquo; builtins instead.
</p>
<p>Not all operations are supported by all target processors.  If a particular
operation cannot be implemented on the target processor, a warning is
generated and a call to an external function is generated.  The external
function carries the same name as the built-in version,
with an additional suffix
&lsquo;<samp class="samp">_<var class="var">n</var></samp>&rsquo; where <var class="var">n</var> is the size of the data type.
</p>

<p>In most cases, these built-in functions are considered a <em class="dfn">full barrier</em>.
That is,
no memory operand is moved across the operation, either forward or
backward.  Further, instructions are issued as necessary to prevent the
processor from speculating loads across the operation and from queuing stores
after the operation.
</p>
<p>All of the routines are described in the Intel documentation to take
&ldquo;an optional list of variables protected by the memory barrier&rdquo;.  It&rsquo;s
not clear what is meant by that; it could mean that <em class="emph">only</em> the
listed variables are protected, or it could mean a list of additional
variables to be protected.  The list is ignored by GCC which treats it as
empty.  GCC interprets an empty list as meaning that all globally
accessible variables should be protected.
</p>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-_005f_005fsync_005ffetch_005fand_005fadd"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_fetch_and_add</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005ffetch_005fand_005fadd"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-_005f_005fsync_005ffetch_005fand_005fsub"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_fetch_and_sub</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005ffetch_005fand_005fsub"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-_005f_005fsync_005ffetch_005fand_005for"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_fetch_and_or</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005ffetch_005fand_005for"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-_005f_005fsync_005ffetch_005fand_005fand"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_fetch_and_and</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005ffetch_005fand_005fand"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-_005f_005fsync_005ffetch_005fand_005fxor"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_fetch_and_xor</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005ffetch_005fand_005fxor"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-_005f_005fsync_005ffetch_005fand_005fnand"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_fetch_and_nand</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005ffetch_005fand_005fnand"> &para;</a></span></dt>
<dd><p>These built-in functions perform the operation suggested by the name, and
returns the value that had previously been in memory.  That is, operations
on integer operands have the following semantics.  Operations on pointer
arguments are performed as if the operands were of the <code class="code">uintptr_t</code>
type.  That is, they are not scaled by the size of the type to which
the pointer points.
</p>
<div class="example smallexample">
<pre class="example-preformatted">{ tmp = *ptr; *ptr <var class="var">op</var>= value; return tmp; }
{ tmp = *ptr; *ptr = ~(tmp &amp; value); return tmp; }   // nand
</pre></div>

<p>The object pointed to by the first argument must be of integer or pointer
type.  It must not be a boolean type.
</p>
<p><em class="emph">Note:</em> GCC 4.4 and later implement <code class="code">__sync_fetch_and_nand</code>
as <code class="code">*ptr = ~(tmp &amp; value)</code> instead of <code class="code">*ptr = ~tmp &amp; value</code>.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-_005f_005fsync_005fadd_005fand_005ffetch"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_add_and_fetch</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>,                                              <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005fadd_005fand_005ffetch"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-_005f_005fsync_005fsub_005fand_005ffetch"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_sub_and_fetch</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005fsub_005fand_005ffetch"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-_005f_005fsync_005for_005fand_005ffetch"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_or_and_fetch</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005for_005fand_005ffetch"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-_005f_005fsync_005fand_005fand_005ffetch"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_and_and_fetch</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005fand_005fand_005ffetch"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-_005f_005fsync_005fxor_005fand_005ffetch"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_xor_and_fetch</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005fxor_005fand_005ffetch"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-_005f_005fsync_005fnand_005fand_005ffetch"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_nand_and_fetch</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005fnand_005fand_005ffetch"> &para;</a></span></dt>
<dd><p>These built-in functions perform the operation suggested by the name, and
return the new value.  That is, operations on integer operands have
the following semantics.  Operations on pointer operands are performed as
if the operand&rsquo;s type were <code class="code">uintptr_t</code>.
</p>
<div class="example smallexample">
<pre class="example-preformatted">{ *ptr <var class="var">op</var>= value; return *ptr; }
{ *ptr = ~(*ptr &amp; value); return *ptr; }   // nand
</pre></div>

<p>The same constraints on arguments apply as for the corresponding
<code class="code">__sync_op_and_fetch</code> built-in functions.
</p>
<p><em class="emph">Note:</em> GCC 4.4 and later implement <code class="code">__sync_nand_and_fetch</code>
as <code class="code">*ptr = ~(*ptr &amp; value)</code> instead of
<code class="code">*ptr = ~*ptr &amp; value</code>.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-_005f_005fsync_005fbool_005fcompare_005fand_005fswap"><span class="category-def">Built-in Function: </span><span><code class="def-type">bool</code> <strong class="def-name">__sync_bool_compare_and_swap</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">oldval</var>, <var class="var">type</var> <var class="var">newval</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005fbool_005fcompare_005fand_005fswap"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-_005f_005fsync_005fval_005fcompare_005fand_005fswap"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_val_compare_and_swap</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">oldval</var>, <var class="var">type</var> <var class="var">newval</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005fval_005fcompare_005fand_005fswap"> &para;</a></span></dt>
<dd><p>These built-in functions perform an atomic compare and swap.
That is, if the current
value of <code class="code">*<var class="var">ptr</var></code> is <var class="var">oldval</var>, then write <var class="var">newval</var> into
<code class="code">*<var class="var">ptr</var></code>.
</p>
<p>The &ldquo;bool&rdquo; version returns <code class="code">true</code> if the comparison is successful and
<var class="var">newval</var> is written.  The &ldquo;val&rdquo; version returns the contents
of <code class="code">*<var class="var">ptr</var></code> before the operation.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-_005f_005fsync_005fsynchronize"><span class="category-def">Built-in Function: </span><span><code class="def-type">void</code> <strong class="def-name">__sync_synchronize</strong> <code class="def-code-arguments">(...)</code><a class="copiable-link" href="#index-_005f_005fsync_005fsynchronize"> &para;</a></span></dt>
<dd><p>This built-in function issues a full memory barrier.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-_005f_005fsync_005flock_005ftest_005fand_005fset"><span class="category-def">Built-in Function: </span><span><code class="def-type"><var class="var">type</var></code> <strong class="def-name">__sync_lock_test_and_set</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, <var class="var">type</var> <var class="var">value</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005flock_005ftest_005fand_005fset"> &para;</a></span></dt>
<dd><p>This built-in function, as described by Intel, is not a traditional test-and-set
operation, but rather an atomic exchange operation.  It writes <var class="var">value</var>
into <code class="code">*<var class="var">ptr</var></code>, and returns the previous contents of
<code class="code">*<var class="var">ptr</var></code>.
</p>
<p>Many targets have only minimal support for such locks, and do not support
a full exchange operation.  In this case, a target may support reduced
functionality here by which the <em class="emph">only</em> valid value to store is the
immediate constant 1.  The exact value actually stored in <code class="code">*<var class="var">ptr</var></code>
is implementation defined.
</p>
<p>This built-in function is not a full barrier,
but rather an <em class="dfn">acquire barrier</em>.
This means that references after the operation cannot move to (or be
speculated to) before the operation, but previous memory stores may not
be globally visible yet, and previous memory loads may not yet be
satisfied.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-_005f_005fsync_005flock_005frelease"><span class="category-def">Built-in Function: </span><span><code class="def-type">void</code> <strong class="def-name">__sync_lock_release</strong> <code class="def-code-arguments">(<var class="var">type</var> *<var class="var">ptr</var>, ...)</code><a class="copiable-link" href="#index-_005f_005fsync_005flock_005frelease"> &para;</a></span></dt>
<dd><p>This built-in function releases the lock acquired by
<code class="code">__sync_lock_test_and_set</code>.
Normally this means writing the constant 0 to <code class="code">*<var class="var">ptr</var></code>.
</p>
<p>This built-in function is not a full barrier,
but rather a <em class="dfn">release barrier</em>.
This means that all previous memory stores are globally visible, and all
previous memory loads have been satisfied, but following memory reads
are not prevented from being speculated to before the barrier.
</p></dd></dl>

</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="_005f_005fatomic-Builtins.html">Built-in Functions for Memory Model Aware Atomic Operations</a>, Previous: <a href="Offsetof.html">Support for <code class="code">offsetof</code></a>, Up: <a href="C-Extensions.html">Extensions to the C Language Family</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
